Using the interpreter

CHICKEN provides an interpreter named csi for evaluating Scheme programs and expressions interactively.

Writing Scheme scripts

Since UNIX shells use the #! notation for starting scripts, anything following the characters #! is ignored, with the exception of the special symbols #!optional, #!key, #!rest and #!eof.

The easiest way is to use the -script option like this:

% cat foo
#! /usr/local/bin/csi -script
(import (chicken port)
        (chicken process-context))
(print (eval (with-input-from-string
                (car (command-line-arguments))
                 read)))

% chmod +x foo
% ./foo "(+ 3 4)"
7

The parameter command-line-arguments is set to a list of the parameters that were passed to the Scheme script. Scripts can be compiled to standalone executables.

CHICKEN supports writing shell scripts in Scheme for other platforms as well, using a slightly different approach. The first example would look like this on Windows:

C:>type foo.bat
@;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
(import (chicken port)
        (chicken process-context))
(print (eval (with-input-from-string
                (car (command-line-arguments))
                read)))

C:>foo "(+ 3 4)"
7

Like UNIX scripts, batch files can be compiled. Windows batch scripts do not accept more than 8 arguments.

Since it is sometimes useful to run a script in the interpreter without actually executing it (for example to test specific parts of it), the option -ss can be used as an alternative to -script. -ss PATHNAME is equivalent to -script PATHNAME but invokes (main (command-line-arguments)) after loading all top-level forms of the script file. The result of main is returned as the exit status to the shell. Any non-numeric result exits with status zero:

% cat hi.scm
(define (main args)
  (print "Hi, " (car args))
  0)
% csi -ss hi.scm you
Hi, you
% csi -q
#;1> ,l hi.scm
#;2> (main (list "ye all"))
Hi, ye all
0
#;3>

When csi is started with the -script option, the feature identifier chicken-script is defined, so can conditionally execute code depending on whether the file is executed as a script or normally loaded into the interpreter, say for debugging purposes:

#!/bin/sh
#| demonstrates a slightly different way to run a script on UNIX systems
exec csi -s "$0" "$@"
|#
(import (chicken process-context))

(define (main args) ...)

(cond-expand
  (chicken-script
    (main (command-line-arguments)))
  (else))

See also the documentation for the -ss option above.

You can also have a look at /writing portable scripts.

Toplevel commands

The toplevel loop understands a number of special commands:

,?
Show summary of available toplevel commands.
,c
Show call-trace items of the most recent error
,ch
Clears stored expression results of previously evaluated expressions.
,d EXP
Describe result of evaluated expression EXP.
,du EXP
Dump contents of the result of evaluated expression EXP.
,dur EXP N
Dump N bytes of the result of evaluated expression EXP.
,e FILENAME
Runs an external editor to edit the given FILENAME (see below for more information).
,exn
Describes the last exception that occurred and adds it to the result history (it can be accessed using the # notation).
,f N
Select call-trace item with the given number, where the number 0 indicates the last item in the trace
,g NAME
Returns the value of the local variable with the given name (which may be a symbol or string); you don't have to give the complete name - ,g will return the first variable that matches the prefix given
,h
Shows all previously evaluated expression results.
,l FILENAME ...
Load files with given FILENAMEs
,ln FILENAME ...
Load files and print result(s) of each top-level expression.
,m MODULENAME
switches the "current module" to MODULENAME, so expressions will be evaluated in the context of the given module. To switch back to toplevel, use #f as a MODULENAME. In compiled modules, only exported bindings will be visible to interactively entered code. In interpreted modules all bindings are visible.
,p EXP
Pretty-print evaluated expression EXP.
,q
Quit the interpreter.
,r
Show system information.
,s TEXT ...
Execute shell-command.
,t EXP
Evaluate form and print elapsed time.
,x EXP
Pretty-print macroexpanded expression EXP (the expression is not evaluated).

You can define your own toplevel commands using the toplevel-command procedure (see Module (chicken csi)).

Get